CHAPTER 3
: Visaj Tutorial
|
This chapter provides a quick tutorial which takes you through the steps required to create the simple application shown in Figure 3-1. As you follow the step-by-step instructions in the tutorial you will be introduced to some of the major features of Visaj.
Figure 3-1 Final application
The tutorial is divided into the following sections:
At the end of each of the three parts listed above, you are given the choice of generating code and stopping the tutorial or continuing. Do as much of the tutorial as you feel you need to get started. Once you have done that, the following sections help you to finish the application:
Remember that Visaj provides extensive online help, see the Online Help section on page 5 for details.
Part One - Building the Hierarchy
The first window displayed by Visaj is the Class Editor. This is described more fully in Chapter 4, "The Class Editor" on page 37.
The tutorial uses two components, the CountingLabel and the Ticker, which are supplied with Visaj for the purpose of demonstrating how to use invisible Beans. To have these components on your palette, you must first load in the JAR file containing them.
|
2. |
Select "Load Jar file..." from the Palette menu. |
|
|
A File Dialog is displayed, ready for the name of the JAR file. |
|
3. |
Select demos.jar from the Visaj install directory1. |
|
|
The extra components are merged into the existing palette. |
Note - Once you have completed this tutorial, you will have a saved design containing some of the beans in demos.jar. In order to open the saved design, you will have to load demos.jar first.
See the Loading JAR Files section on page 60 for more information on this topic.
|
4. |
Click on the Frame icon from the component palette along the left hand side of the window. |
At this point, a separate window appears on the screen. This is the dynamic display and shows exactly the user interface that you are building.
|
5. |
Click on the MenuBar icon. |
|
|
The containment hierarchy now shows the Frame with a MenuBar child. Since the MenuBar is a container Visaj has automatically selected this component in the hierarchy ready for the Menu children to be added. |
|
6. |
Add a Menu component and 2 MenuItems to the design. |
|
7. |
Click on the Frame at the root of the hierarchy. |
|
8. |
Add a Panel from the Containers section and two Buttons from the Basic section. |
|
|
The Buttons are added as children of the Panel. |
|
|
You should now have the hierarchy shown in Figure 3-2. |
Figure 3-2 Initial hierarchy
|
9. |
Select menuBar1 and select "Fold/Unfold nodes" from the View menu to fold this part of the hierarchy. |
|
|
Alternatively, you can click over the small box under MenuBar1. This is the Fold/Unfold icon. |
|
10. |
Select panel1 and again choose Fold from the View menu, or click over the small box under Panel1. |
|
11. |
Add a Toolbar from the Diamonds section to your Frame. |
|
12. |
Add two ArrowButtons, also from the Diamonds section, to your Toolbar. |
|
13. |
Add a StatusBar (from the Diamonds) to the Frame. |
|
14. |
Add a Label (from Basic) and a CountingLabel (from the demos.jar section) to the StatusBar. |
|
|
The CountingLabel is one of the Beans loaded from demos.jar. A separate section for all the Beans found in that file is added to the bottom of the object palette. |
|
15. |
Select the Frame again and add a TextArea (from Basic) to it. |
|
16. |
Make sure no objects are selected by clicking over the design area background. |
|
|
To add invisible Beans, there must be no current selection. |
|
17. |
Add a Ticker invisible Bean to your design. This is found in the demos.jar section at the bottom of the object palette. |
|
|
Invisible Beans appear at the top of the design area alongside hierarchy root objects, as shown in Figure 3-3. |
Figure 3-3 Full window hierarchy
Now that you have finished adding components and Beans, your dynamic display should appear as shown in Figure 3-4.
Figure 3-4 Initial window
|
18. |
Choose "Save" from the File menu and type "mydesign.vcl" into the File Dialog. |
|
|
The "vcl" suffix is a convention for Class Editor save files. It is good practice to save your design at regular intervals. |
Setting Properties
Having added the components to the design we now need to set some properties.
|
19. |
Unfold the MenuBar branch of the hierarchy and double-click on menu1 to display the Property Sheet. |
|
|
By default, double-clicking on an object displays the object's Property Sheet. Alternatively, you can display the Property Sheet by pressing the toolbar icon shown in Figure 3-5. |
Figure 3-5 Property Sheet Icon on Toolbar
|
20. |
Select "label" from the java.awt.MenuItem group of properties. The Editor for this property type appears at the bottom of the panel. Change the label from "menu1" to "File". |
More information on the setting of properties and the effect this has is given in the "Properties" section on page 60.
We have some more properties to set. There is no need to close the Property Sheet and redisplay it, as it updates according to the current selection. If there is no selection, the title of the Property Sheet changes to reflect this.
|
21. |
With the Property Sheet still displayed select first menuItem1 and then menuItem2 changing the labels to "Open" and "Exit" respectively. |
|
22. |
Click on the background to deselect all objects in the design area. |
|
|
Either click the fold icon underneath it or select "Fold/Unfold nodes" from the View menu. |
|
24. |
Use the mouse to draw a band around the two button children of the panel (click and hold the mouse button down to draw a box around the two buttons). |
Multiple selection can be used to modify the properties of many components simultaneously.
|
25. |
Change the background color property to "orange". The change is applied immediately to both buttons. |
|
|
Because the two labels are highlighted in the dynamic display, it looks as though the foreground color has been set. When you select something other than the labels, you can see the correct background color. |
|
26. |
Select button1, with the Property Sheet still displayed, and change its label property to "Show". |
|
27. |
Select button2 and change its label property to "Hide". |
|
28. |
Select the label child of the StatusBar and change the text property to "Counter:". |
|
29. |
Close the Property Sheet. |
|
|
It is good practice to save your design at regular intervals. |
You have now created a simple design with a default layout. If you wish to stop following the tutorial at this point, go straight to the Generating Code section on page 33. That section describes how to generate code for your application. You may continue the tutorial in the following section, which describes the Layout Editor and adds a dialog to the new user interface.
Part Two - Layouts
All container type components, such as the Frame, have a layout property associated with them. This layout allows you to arrange the container's children in a pre-defined manner. You can change the layout type of a container, as with any other property - this is demonstrated in Step 37 below. Visaj provides interactive dialogs which help you to arrange the container's children according to the rules of the container's layout. See the Layout Editors section on page 69 for details on these.
This section of the tutorial demonstrates the editors for the BorderLayout and the GridBagLayout. The GridBagLayout belongs to the new sub-dialog, which is added in this section.
The layout of a Frame container defaults to a BorderLayout. The BorderLayout allows you to position components in North, East, South, West and Central positions. Visaj's powerful layout editors make this easy.
|
31. |
With the Frame selected in the hierarchy, press the Layout Editor button in the toolbar. The BorderLayout Editor dialog appears as shown in Figure 3-6. |
Figure 3-6 Border Layout Editor: first view
|
32. |
Use the mouse to drag the components to the correct positions so that they appear as shown in Figure 3-7. |
Figure 3-7 Border Layout Editor after arranging components
|
33. |
Close the Layout Editor. |
|
|
It is good practice to save your design at regular intervals. |
Adding Another Dialog
The next stage of the tutorial shows how to add a sub-dialog to your design. Dialog components need a parent, so we are going to make it a child of the Frame.
|
35. |
Select the Frame, if it is not selected already. |
|
36. |
Add a Dialog, from the object palette, to the Frame. |
|
|
This is found in the Containers section. |
|
37. |
With dialog1 selected, display its Property Sheet. |
|
38. |
Select the layout property from the java.awt.Container section and choose GridBagLayout from the option menu at the bottom of the Property Sheet. |
|
39. |
Add 4 Labels and 4 TextField children to the dialog. |
|
40. |
Add a Checkbox to the dialog. |
|
41. |
Select the Checkbox and change its "label" property to "Keep me on screen". |
Go back to the "Setting Properties" section on page 18 if you need a reminder of how to do this.
GridBag Layout Editor
|
42. |
Select the dialog and display the GridBagLayout Editor using the Layout Editor toolbar button. |
Figure 3-8 Layout Editor Toolbar Icon
|
43. |
Drag the components in the editor to achieve the layout shown in Figure 3-9. |
See the GridBag section on page 72 for a detailed description of the GridBag Layout Editor.
Figure 3-9 GridBag Layout Editor
|
44. |
Select checkbox1 in the Layout Editor and drag the right edge so that it fills two columns, as shown in Figure 3-9. |
|
|
This is so that the all the labels in the first column are not forced to be the same width as the Checkbox. |
|
45. |
With Checkbox1 still selected, set the Anchor option menu to "West" and the Fill option menu to "None". Press "Apply". |
|
|
This puts the Checkbox on the left and stops it trying to fill both columns. |
|
46. |
Select label2, unset the RelativeX and RelativeY toggles and press "Apply". |
|
|
The other components lost their relative x and y settings when they were moved. Relative x and y settings are not required for this tutorial. |
|
47. |
Hold down the shift key and click on each of the components except the Checkbox. |
|
|
We have already set the Fill option for the Checkbox. |
|
48. |
Change the Fill option menu from "None" to "Both" and press "Apply". |
|
49. |
Click in an empty cell to deselect the components. |
|
50. |
Hold down the shift key and click on the two TextFields in the top row of the grid. Change the Column Weight to "1" and press "Apply". Repeat for the two Labels in the top row and change the Column Weight to "2" and press "Apply". |
|
|
The column weight affects the way objects stretch when the container grows horizontally. |
|
51. |
Close the GridBag Layout Editor. |
|
52. |
Select one of the four Labels which are children of dialog1. Use multiple selection (Shift + mouse button 1) to select the other three as well. |
|
53. |
Change the text property of the 4 Labels to "Input". |
|
54. |
Select the four Textfields and change the columns property to "10". |
If you wish to stop following the tutorial at this point, go straight to Generating Code on page 33. The tutorial continues in the following section with actions being added to some of the buttons in the design.
Part Three - Adding Event Bindings
For the last stage of the tutorial, we shall add some basic functionality to the application. We will set up the buttons in the Panel to hide and show dialog1, set up the Ticker and CountingLabel so that they display the amount of time the dialog is shown on the screen and set up the Exit button in the File menu to exit the application.
For more information on event bindings, see Chapter 6, "Event Bindings", starting on page 79.
|
56. |
Fold away the components underneath dialog1 and under the ToolBar and StatusBar. |
|
|
Do this so that you can see both the buttons and dialog1 in order to complete the next step. You may also need to press the "Method Editors Only" toolbar button. This is shown in Figure 3-10. |
Figure 3-10 Method Editors Only Toolbar Icon
|
57. |
With the Control key held down, use your mouse to drag a line from button1 to dialog1. |
|
|
This is a fast way of displaying the Event Binding Editor for a new binding, primed with the two objects at either end of the line drawn in the design area. |
There are two other ways of displaying the Event Binding Editor:
|
1. |
Selecting the "Event bindings" tab panel on the left of the Class Editor window and pressing the "New" or "Edit" buttons. |
|
2. |
Pressing the Event Binding button on the toolbar, shown in Figure 3-11. |
Figure 3-11 Event Binding Icon on Toolbar
See Chapter 6, "Event Bindings", starting on page 79 for a full description of the Event Binding Editor.
|
58. |
Check that the Source of the event binding is "button1" and the Destination Object is "dialog1". |
|
59. |
Set the Type to "actionPerformed" and select the Handler Method "show()". This is shown in Figure 3-12. |
|
|
Make sure that you select the "show" method which has no parameters. The "show" method with parameters is a deprecated method. |
Figure 3-12 Event Editor
|
60. |
Press the "Finish" button. |
|
|
The completed event binding now appears in the Event Binding List. Pressing "Another" also creates the event binding, leaving the dialog on the screen ready for you to add another binding. |
|
61. |
Add another new event binding so that the Source is "button2", the Type is "actionPerformed", the Object is "dialog1" and the Method is "setVisible". |
|
|
This method has a parameter; when you select it the "Next>" button becomes enabled. The "Finish" button is not enabled, showing that you have not completed the specification of the event binding. |
|
62. |
Press the "Next>" button. The second page of the Event Binding Editor is displayed, as shown in Figure 3-13. |
|
|
Now that you are on the second page, the "<Previous" button is enabled, allowing you to move back to the first page. The "Finish" button will not become enabled until you have entered a value for the parameter. |
Figure 3-13 Event Binding Editor Second Page
|
63. |
Select the boolean parameter, select "Value" from the list on the right and change the option menu to "False". |
|
|
setVisible(false) hides the dialog. |
|
64. |
Press "Finish" to create this event binding. |
Try out the two new event bindings in the dynamic display. Press button2 - the dialog disappears. Press button1 - it reappears. We are now going to change this last event binding so that it hides the dialog only if the Checkbox in the dialog is not set.
|
65. |
Edit the last event binding. |
|
|
Select the last event binding from the Event Bindings List in the Class Editor and press "Edit". This is shown in Figure 3-14. |
Figure 3-14 Event Binding to Edit
|
66. |
On the parameters page of the Event Binding Editor, select the boolean parameter. |
|
|
The tick next to this parameter indicates that it has already been configured. The area on the right shows that you have set an explicit value for this parameter. |
|
67. |
Select "Property" from the list on the right. |
|
|
We are going to set the value of the parameter according to the property of another object. Two lists appear in the lower right of the Editor to allow you to select any object from your design and any properties of that object which have the same type as the selected parameter. |
|
68. |
Select "checkbox1" (beneath "dialog1") from the list of objects in the design. |
|
69. |
Select "state" from the list of properties. |
Figure 3-15 Checkbox Property for Boolean Parameter
|
|
The binding is now set so that when the Checkbox is set, the dialog does not disappear. When the Checkbox is not set, the dialog does disappear. Try it out in the dynamic display. |
Event Bindings for Invisible Beans
To demonstrate how the invisible Beans work, we are now going to add some more event bindings to make the CountingLabel count tenths of a second while the dialog is displayed.
|
71. |
Add another new event to the Show button (button1) to make the Ticker start, as shown in Figure 3-16. |
|
|
The Source is "button1", the Type is "actionPerformed", the Destination Object is "ticker1" and the Method is "start()". |
Figure 3-16 Ticker Start Event
|
72. |
Add another new event binding to button2 to stop the ticker, as shown in Figure 3-17. |
|
|
For this binding, the Source is "button2", the Type is "actionPerformed", the Object is "ticker1" and the Method is "stop()". |
Figure 3-17 Ticker Stop Event
|
73. |
Now add a new event to the Ticker itself to increment the CountingLabel as it ticks, as shown in Figure 3-18. |
|
|
The Source is "ticker1", the Type is "tick", the Destination Object is "countingLabel1" and the Method is "increment()". |
Figure 3-18 Ticker Tick and Increment Event
|
74. |
Try pressing the buttons in the dynamic display again and watch the CountingLabel show the seconds that pass when the dialog is displayed. |
Event Bindings to Other Methods
Finally we are going to create a new method called "myExit" which will be called when the user selects the File/Exit button.
To do this, we shall add another method to our class. If you have hidden the Class Structure View, bring it back by pressing the "Show Method Editors and Class Structure" button on the toolbar. This button is shown in Figure 3-19.
Figure 3-19 Toolbar Icon to Redisplay Class Structure
|
75. |
Select "Properties..." from the Class menu of the Class Editor. |
|
76. |
Double click on the class name, change "MyClass" to "MyFirstVisajApp" and press "Apply". |
Note - The name of the method in your class also changes because it is the constructor and therefore must have the same name as the class.
|
77. |
Close the Properties dialog. |
|
78. |
Select "Add new method" from the Method menu to add a new method to the class. |
|
|
A method named "method2" appears in the class structure. |
|
80. |
Display the "Signature" tab panel from the Method Designer and change the name of method2 to "myExit". |
|
81. |
Select the "MyFirstVisajApp" method in the Class Structure view again and display the Event Binding Editor. |
|
82. |
Add a new event binding such that the Source is "menuItem2", the Type is "actionPerformed", the Destination Object is "MyFirstVisajApp.this" and the Method is "myExit()", as shown in Figure 3-20. |
|
|
Make sure that "MyFirstVisajApp" is selected in the Class Structure View before adding this event binding. |
Figure 3-20 Calling New Methods in Event Binding Editor
The application design is now complete. The following section explains how to generate the code for the design.
Generating Code
|
1. |
Select the constructor (MyFirstVisajApp) in the Class Structure View and set the "Main method" checkbox in the Method menu. |
|
|
This tells Visaj to generate a main method and call the constructor. |
See the "Main Method" section on page 49 for more information on generating a main method from Visaj.
|
2. |
Select "Generate java..." from the Generate menu, specify a target directory in the directory selection box and press "OK". |
|
3. |
Save your Visaj design. |
|
|
You can now exit Visaj if you wish. |
|
|
Remember that if you wish to reload your design into Visaj, you will have to load the demos.jar file beforehand, as described in Step 2 and Step 3 on page 14. |
Adding Your Own Code
You only need to do this part if you completed Part Three - Adding Event Bindings. If you did not, then go straight to the Compiling and Running section on page 35. All of the following is done external to Visaj.
This tutorial shows you how to edit the generated code directly. See the "Adding Your Own Code - Subclassing" section on page 153 for a description of another way of adding code.
|
1. |
Edit the generated file, MyFirstVisajApp.java. |
|
2. |
Find the "myExit" method and add the call to "System.exit(0)". Make sure that you add your code outside of the special comments, so that it is retained if you regenerate the code. |
|
|
The line to add is shown below. |
protected void myExit() {
//vj- <VJ-BeginMethodDef>
//vj= <VJ-MethodCode>
//vj+ <VJ-DefineAWTMembers>
//vj- <VJ-DefineAWTMembers>
//vj+ <VJ-EndAWT>
//vj- <VJ-EndAWT>
//vj+ <VJ-EventListenerClass>
//vj- <VJ-EventListenerClass>
//vj+ <VJ-AddEventListeners>
//vj- <VJ-AddEventListeners>
//vj= <VJ-Classes>
Add the next line:
System.exit(0);
//vj+ <VJ-EndMethodDef>
}
See the Editing the Code section on page 154 for more information on where you may safely insert your code.
Compiling and Running
You now have the source of your application. Perform the following steps outside of Visaj.
|
1. |
Add the diamonds.jar and demos.jar files from the Visaj install directory and the current directory (.) to your CLASSPATH. Compile the code. |
|
2. |
Compile your application. |
|
|
Remember that the java compiler is case sensitive. You should specify MyFirstJavaApp.java as the file to compile using exactly that capitalization. |
|
3. |
When the code has compiled, run your application. |
1
The install directory is where Visaj has been installed by the installer, not the temporary area where
Visaj is "unpacked" on Microsoft Windows.
Copyright
© 1998, 1999 Pacific Imperial Inc.,
TakeFive Software Inc.
All Rights Reserved.